/* http_fetcher.h - HTTP handling functions

    HTTP Fetcher
    Copyright (C) 2001, 2003 Lyle Hanson (lhanson@users.sourceforge.net)

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    See LICENSE file for details
                                    
 */

#ifndef HTTP_FETCHER_H
#define HTTP_FETCHER_H

#define VERSION "2.0.0"
#ifdef WIN32
#define DllExport  __declspec(dllexport)
#else
#define DllExport /**/
#endif

#define HTTP_VERSION            "HTTP/1.0"
#define DEFAULT_USER_AGENT      "HTTP Fetcher"
#define DEFAULT_PORT_NUMBER     80
#define DEFAULT_PROXY_PORT      8080
#define DEFAULT_READ_TIMEOUT    30      /* Seconds to wait before giving up
                                         *  when no data is arriving */
     
#define DEFAULT_REQUEST_BUF_SIZE 1024
#define DEFAULT_HEADER_BUFSIZE         1024
#define DEFAULT_PAGE_BUF_SIZE   (1024 * 200) /* 200K should hold most things */



/*****************************************************************************/
/**************** Function declarations and descriptions *********************/
/*****************************************************************************/

/* 
 * [!!! NOTE !!!]  All HTTP Fetcher functions return -1 or NULL on error.
 *  You can then either call hfetcher_perror to print the error message or call
 *  hfetcher_strerror to get a pointer to it.  Calling another HTTP Fetcher
 *  function may overwrite the error value from the previous error.
 */


    /*
     * Download the page, registering a hit. If you pass it a NULL for fileBuf,
     *  'url' will be requested but will not remain in memory (useful for
     *  simply registering a hit).  Otherwise necessary space will be allocated
     *  and will be pointed to by fileBuf.
     * The number of bytes downloaded (excluding metadata) is stored in
     *  'fileSize'.  Note that the buffer is actually fileSize + 1 in size
     *  because a NULL byte is appended to the data.
     * Returns:
     *  status code of HTTP request
     *  -1 on error
     */
DllExport int hfetcher_fetch(const char *url, char **fileBuf, int *fileSize);

    /*
     * Use the specified host as a proxy server.  Default port is 8080 unless
     *  'newProxy' ends in a colon followed by a port number.  Send it NULL to
     *  disable proxy use (if a proxy was previously set).
     * Returns:
     *  0 on success, or
     *  -1 on error (previous proxy remains unchanged)
     */
DllExport int hfetcher_setProxy(const char *newProxy);

    /*
     * Changes the User Agent (shown to the web server with each request)
     *  Send it NULL to avoid telling the server a User Agent
     *  By default, the User Agent is sent (The default one unless changed)
     * Returns:
     *  0 on success, or
     *  -1 on error (previous value for agent remains unchanged)
     */
DllExport int hfetcher_setUserAgent(const char *newAgent);

    /*
     * Changes the Referer (shown to the web server with each request)
     *  Send it NULL to avoid thelling the server a Referer
     *  By default, no Referer is sent
     * Returns:
     *  0 on success, or
     *  -1 on error (previous referer remains unchanged)
     */
DllExport int hfetcher_setReferer(const char *newReferer);

    /*
     * Changes the maximum amount of time that HTTP Fetcher will wait on
     *  data.  If this many seconds elapses without more data from the
     *  server, hfetcher_fetch will return with an error.
     * If you pass a value less than 0, reads will not time out, potentially
     *  waiting forever (or until data shows up, whichever comes first)
     */
DllExport void hfetcher_setTimeout(int seconds);

    /*
     * Takes a url and puts the filename portion of it into 'filename'.
     * Returns:
     *  0 on success, or
     *  1 when url contains no end filename (i.e., "www.foo.com/")
     *      and **filename should not be assumed to point to anything), or
     *  -1 on error
     */
DllExport int hfetcher_parseFilename(const char *url, char **filename);

    /*
     * Stores a pointer to the response header (metadata) of the last http
     *  request in headerData.
     * Returns:
     *  The length of the header buffer, or
     *  -1 on error
     */
DllExport int hfetcher_returnHeader(char **headerData);

    /*
     * Works like perror.  If an HTTP Fetcher function ever returns an
     *  error (-1), this will print a descriptive message to standard error.
     */
DllExport void hfetcher_perror(const char *string);

    /*
     * Returns a pointer to the current error description message.  The
     *  message pointed to is only good until the next call to
     *  hfetcher_strerror(), so if you need to hold on to the message for a
     *  while you should make a copy of it.
     */
DllExport const char *hfetcher_strerror(void);



/******************************************************************************/
/**** Internally used functions declared in "http_fetcher_internal.h"         */
/******************************************************************************/

#endif
